All Packages Class Hierarchy This Package Previous Next Index
Class com.sun.java.swing.text.AbstractDocument
java.lang.Object
|
+----com.sun.java.swing.text.AbstractDocument
- public abstract class AbstractDocument
- extends Object
- implements Document, Serializable
An implementation of the document interface to serve as a
basis for implementing various kinds of documents. At this
level there is very little policy, so there is a corresponding
increase in difficulty of use.
This class implements a locking mechanism for the document. It
allows multiple readers or one writer, and writers must wait until
all observers of the document have been notified of a previous
change before beginning another mutation to the document. The
read lock is aquired and released using the render
method. A write lock is aquired by the methods that mutate the
document, and are held for the duration of the method call.
Notification is done on the thread that produced the mutation,
and the thread has full read access to the document for the
duration of the notification, but other readers are kept out
until the notification has finished. The notification is a
beans event notification which does not allow any further
mutations until all listeners have been notified.
Any models subclassed from this class and used in conjunction
with a text component that has a look and feel implementation
that is derived from DefaultTextUI may be safely updated
asynchronously. The rendering in DefaultTextUI occurs under
the protection of the render
method, which makes
rendering safe if it is running on the event thread (which
happens if using repaint to schedule updates). The code path
for any DocumentListener implementation must not access the
component lock if trying to be safe from deadlocks.
The repaint and revalidate
methods
on JComponent are safe.
Warning: serialized objects of this class will not be compatible with
future swing releases. The current serialization support is appropriate
for short term storage or RMI between Swing1.0 applications. It will
not be possible to load serialized Swing1.0 objects with future releases
of Swing. The JDK1.2 release of Swing will be the compatibility
baseline for the serialized form of Swing objects.
-
BAD_LOCATION
- Error message to indicate a bad location.
-
ContentElementName
- Name of elements used to represent content
-
ElementNameAttribute
- Name of the attribute used to specify element
names.
-
listenerList
- The event listener list for the document.
-
ParagraphElementName
- Name of elements used to represent paragraphs
-
SectionElementName
- Name of elements used to hold sections (lines/paragraphs).
-
AbstractDocument(AbstractDocument. Content)
- Constructs a new AbstractDocument, wrapped around some
specified content storage mechanism.
-
AbstractDocument(AbstractDocument. Content, AbstractDocument. AttributeContext)
- Constructs a new AbstractDocument, wrapped around some
specified content storage mechanism.
-
addDocumentListener(DocumentListener)
- Adds a document listener for notification of any changes.
-
addUndoableEditListener(UndoableEditListener)
- Adds an undo listener for notification of any changes.
-
createBranchElement(Element, AttributeSet)
- Creates a document branch element, that can contain other elements.
-
createLeafElement(Element, AttributeSet, int, int)
- Creates a document leaf element.
-
createPosition(int)
- Returns a position that will track change as the document
is altered.
-
dump(PrintStream)
- Gives a diagnostic dump.
-
fireChangedUpdate(DocumentEvent)
- Notifies all listeners that have registered interest for
notification on this event type.
-
fireInsertUpdate(DocumentEvent)
- Notifies all listeners that have registered interest for
notification on this event type.
-
fireRemoveUpdate(DocumentEvent)
- Notifies all listeners that have registered interest for
notification on this event type.
-
fireUndoableEditUpdate(UndoableEditEvent)
- Notifies all listeners that have registered interest for
notification on this event type.
-
getAttributeContext()
- Fetches the context for managing attributes.
-
getContent()
- Gets the content for the document.
-
getCurrentWriter()
- Fetches the current writing thread if there is one.
-
getDefaultRootElement()
- Returns the root element that views should be based upon
unless some other mechanism for assigning views to element
structures is provided.
-
getDocumentProperties()
- Support for managing a set of properties.
-
getEndPosition()
- Returns a position that represents the end of the document.
-
getLength()
- Returns the length of the data.
-
getProperty(Object)
- A convenience method for looking up a property value.
-
getRootElements()
- Gets all root elements defined.
-
getStartPosition()
- Returns a position that represents the start of the document.
-
getText(int, int)
- Gets a sequence of text from the document.
-
getText(int, int, Segment)
- Gets some text from the document potentially without
making a copy.
-
insertString(int, String, AttributeSet)
- Inserts some content into the document.
-
insertUpdate(AbstractDocument. DefaultDocumentEvent, AttributeSet)
- Updates document structure as a result of text insertion.
-
putProperty(Object, Object)
- A convenience method for storing up a property value.
-
readLock()
- Acquires a lock to begin reading some state from the
document.
-
readUnlock()
- Does a read unlock.
-
remove(int, int)
- Removes some content from the document.
-
removeDocumentListener(DocumentListener)
- Removes a document listener.
-
removeUndoableEditListener(UndoableEditListener)
- Removes an undo listener.
-
removeUpdate(AbstractDocument. DefaultDocumentEvent)
- Updates any document structure as a result of text removal.
-
render(Runnable)
- This allows the model to be safely rendered in the presence
of currency, if the model supports being updated asynchronously.
-
setDocumentProperties(Dictionary)
- Replace the document properties dictionary for this document.
-
writeLock()
- Acquires a lock to begin mutating the document this lock
protects.
-
writeUnlock()
- Releases the write lock held because the write
operation is finished.
listenerList
protected EventListenerList listenerList
- The event listener list for the document.
BAD_LOCATION
protected static final String BAD_LOCATION
- Error message to indicate a bad location.
ParagraphElementName
public static final String ParagraphElementName
- Name of elements used to represent paragraphs
ContentElementName
public static final String ContentElementName
- Name of elements used to represent content
SectionElementName
public static final String SectionElementName
- Name of elements used to hold sections (lines/paragraphs).
ElementNameAttribute
public static final String ElementNameAttribute
- Name of the attribute used to specify element
names.
AbstractDocument
protected AbstractDocument(AbstractDocument. Content data)
- Constructs a new AbstractDocument, wrapped around some
specified content storage mechanism.
- Parameters:
- data - the content
AbstractDocument
protected AbstractDocument(AbstractDocument. Content data,
AbstractDocument. AttributeContext context)
- Constructs a new AbstractDocument, wrapped around some
specified content storage mechanism.
- Parameters:
- data - the content
- context - the attribute context
getDocumentProperties
public Dictionary getDocumentProperties()
- Support for managing a set of properties. Callers
can use the documentProperties dictionary to annotate the
document with document-wide properties.
- Returns:
- a non null Dictionary
- See Also:
- setDocumentProperties
setDocumentProperties
public void setDocumentProperties(Dictionary x)
- Replace the document properties dictionary for this document.
- Parameters:
- x - the new dictionary
- See Also:
- getDocumentProperties
fireInsertUpdate
protected void fireInsertUpdate(DocumentEvent e)
- Notifies all listeners that have registered interest for
notification on this event type. The event instance
is lazily created using the parameters passed into
the fire method.
- Parameters:
- e - the event
- See Also:
- EventListenerList
fireChangedUpdate
protected void fireChangedUpdate(DocumentEvent e)
- Notifies all listeners that have registered interest for
notification on this event type. The event instance
is lazily created using the parameters passed into
the fire method.
- Parameters:
- e - the event
- See Also:
- EventListenerList
fireRemoveUpdate
protected void fireRemoveUpdate(DocumentEvent e)
- Notifies all listeners that have registered interest for
notification on this event type. The event instance
is lazily created using the parameters passed into
the fire method.
- Parameters:
- e - the event
- See Also:
- EventListenerList
fireUndoableEditUpdate
protected void fireUndoableEditUpdate(UndoableEditEvent e)
- Notifies all listeners that have registered interest for
notification on this event type. The event instance
is lazily created using the parameters passed into
the fire method.
- Parameters:
- e - the event
- See Also:
- EventListenerList
render
public void render(Runnable r)
- This allows the model to be safely rendered in the presence
of currency, if the model supports being updated asynchronously.
The given runnable will be executed in a way that allows it
to safely read the model with no changes while the runnable
is being executed. The runnable itself may not
make any mutations.
This is implemented to aquire a read lock for the duration
of the runnables execution. There may be multiple runnables
executing at the same time, and all writers will be blocked
while there are active rendering runnables. If the runnable
throws an exception, its lock will be safely released.
There is no protection against a runnable that never exits,
which will effectively leave the document locked for it's
lifetime.
If the given runnable attempts to make any mutations in
this implementation, a deadlock will occur. There is
no tracking of individual rendering threads to enable
detecting this situation, but a subclass could incur
the overhead of tracking them and throwing an error.
This method is thread safe, although most Swing methods
are not. Please see
Threads
and Swing for more information.
- Parameters:
- r - the renderer to execute.
getLength
public int getLength()
- Returns the length of the data. This is the number of
characters of content that represents the users data.
- Returns:
- the length >= 0
- See Also:
- getLength
addDocumentListener
public void addDocumentListener(DocumentListener listener)
- Adds a document listener for notification of any changes.
- Parameters:
- listener - the listener
- See Also:
- addDocumentListener
removeDocumentListener
public void removeDocumentListener(DocumentListener listener)
- Removes a document listener.
- Parameters:
- listener - the listener
- See Also:
- removeDocumentListener
addUndoableEditListener
public void addUndoableEditListener(UndoableEditListener listener)
- Adds an undo listener for notification of any changes.
Undo/Redo operations performed on the UndoableEdit will
cause the appropriate DocumentEvent to be fired to keep
the view(s) in sync with the model.
- Parameters:
- listener - the listener
- See Also:
- addUndoableEditListener
removeUndoableEditListener
public void removeUndoableEditListener(UndoableEditListener listener)
- Removes an undo listener.
- Parameters:
- listener - the listener
- See Also:
- removeDocumentListener
getProperty
public final Object getProperty(Object key)
- A convenience method for looking up a property value. It is
equivalent to:
getDocumentProperties().get(key);
- Parameters:
- key - the non-null property key
- Returns:
- the value of this property or null
- See Also:
- getDocumentProperties
putProperty
public final void putProperty(Object key,
Object value)
- A convenience method for storing up a property value. It is
equivalent to:
getDocumentProperties().put(key, value);
If value is null this method will remove the property
- Parameters:
- key - the non-null key
- value - the value
- See Also:
- getDocumentProperties
remove
public void remove(int offs,
int len) throws BadLocationException
- Removes some content from the document.
Removing content causes a write lock to be held while the
actual changes are taking place. Observers are notified
of the change on the thread that called this method.
This method is thread safe, although most Swing methods
are not. Please see
Threads
and Swing for more information.
- Parameters:
- offs - the starting offset >= 0
- len - the number of characters to remove >= 0
- Throws: BadLocationException
- the given remove position is not a valid
position within the document
- See Also:
- remove
insertString
public void insertString(int offs,
String str,
AttributeSet a) throws BadLocationException
- Inserts some content into the document.
Inserting content causes a write lock to be held while the
actual changes are taking place, followed by notification
to the observers on the thread that grabbed the write lock.
This method is thread safe, although most Swing methods
are not. Please see
Threads
and Swing for more information.
- Parameters:
- offs - the starting offset >= 0
- str - the string to insert; does nothing with null/empty strings
- a - the attributes for the inserted content
- Throws: BadLocationException
- the given insert position is not a valid
position within the document
- See Also:
- insertString
getText
public String getText(int offset,
int length) throws BadLocationException
- Gets a sequence of text from the document.
- Parameters:
- offset - the starting offset >= 0
- length - the number of characters to retrieve >= 0
- Returns:
- the text
- Throws: BadLocationException
- the range given includes a position
that is not a valid position within the document
- See Also:
- getText
getText
public void getText(int offset,
int length,
Segment txt) throws BadLocationException
- Gets some text from the document potentially without
making a copy. The character array returned in the
given
Segment
should never be mutated.
This kind of access to the characters of the document
is provided to help make the rendering potentially more
efficient. The caller should make no assumptions about
the lifetime of the returned character array, which
should be copied if needed beyond the use for rendering.
- Parameters:
- offset - the starting offset >= 0
- length - the number of characters to retrieve >= 0
- txt - the Segment object to retrieve the text into
- Throws: BadLocationException
- the range given includes a position
that is not a valid position within the document
createPosition
public synchronized Position createPosition(int offs) throws BadLocationException
- Returns a position that will track change as the document
is altered.
This method is thread safe, although most Swing methods
are not. Please see
Threads
and Swing for more information.
- Parameters:
- offs - the position in the model >= 0
- Returns:
- the position
- Throws: BadLocationException
- if the given position does not
represent a valid location in the associated document
- See Also:
- createPosition
getStartPosition
public final Position getStartPosition()
- Returns a position that represents the start of the document. The
position returned can be counted on to track change and stay
located at the beginning of the document.
- Returns:
- the position
getEndPosition
public final Position getEndPosition()
- Returns a position that represents the end of the document. The
position returned can be counted on to track change and stay
located at the end of the document.
- Returns:
- the position
getRootElements
public Element[] getRootElements()
- Gets all root elements defined. Typically, there
will only be one so the default implementation
is to return the default root element.
- Returns:
- the root element
getDefaultRootElement
public abstract Element getDefaultRootElement()
- Returns the root element that views should be based upon
unless some other mechanism for assigning views to element
structures is provided.
- Returns:
- the root element
- See Also:
- getDefaultRootElement
getAttributeContext
protected final AbstractDocument. AttributeContext getAttributeContext()
- Fetches the context for managing attributes. This
method effectively establishes the strategy used
for compressing AttributeSet information.
- Returns:
- the context
insertUpdate
protected void insertUpdate(AbstractDocument. DefaultDocumentEvent chng,
AttributeSet attr)
- Updates document structure as a result of text insertion. This
will happen within a write lock. If a subclass of
this class reimplements this method, it should delegate to the
superclass as well.
- Parameters:
- chng - a description of the change
- attr - the attributes for the change
removeUpdate
protected void removeUpdate(AbstractDocument. DefaultDocumentEvent chng)
- Updates any document structure as a result of text removal.
This will happen within a write lock. If a subclass
of this class reimplements this method, it should delegate to the
superclass as well.
- Parameters:
- chng - a description of the change
dump
public void dump(PrintStream out)
- Gives a diagnostic dump.
- Parameters:
- out - the output stream
getContent
protected final AbstractDocument. Content getContent()
- Gets the content for the document.
- Returns:
- the content
createLeafElement
protected Element createLeafElement(Element parent,
AttributeSet a,
int p0,
int p1)
- Creates a document leaf element.
Hook through which elements are created to represent the
document structure. Because this implementation keeps
structure and content seperate, elements grow automatically
when content is extended so splits of existing elements
follow. The document itself gets to decide how to generate
elements to give flexibility in the type of elements used.
- Parameters:
- parent - the parent element
- a - the attributes for the element
- p0 - the beginning of the range >= 0
- p1 - the end of the range >= p0
- Returns:
- the new element
createBranchElement
protected Element createBranchElement(Element parent,
AttributeSet a)
- Creates a document branch element, that can contain other elements.
- Parameters:
- parent - the parent element
- a - the attributes
- Returns:
- the element
getCurrentWriter
protected final synchronized Thread getCurrentWriter()
- Fetches the current writing thread if there is one.
This can be used to distinguish whether a method is
being called as part of an existing modification or
if a lock needs to be acquired and a new transaction
started.
- Returns:
- s the thread actively modifying the document
or null if there are no modifications in progress
writeLock
protected final synchronized void writeLock()
- Acquires a lock to begin mutating the document this lock
protects. There can be no notification of changes or
reading going on in order to gain the lock.
writeUnlock
protected final synchronized void writeUnlock()
- Releases the write lock held because the write
operation is finished. This allows either a new
writer or readers to aquire a lock.
readLock
protected final synchronized void readLock()
- Acquires a lock to begin reading some state from the
document. There can be multiple readers at the same time
and reading can occur while notification to the listeners
is going on, but writing blocks the readers.
readUnlock
protected final synchronized void readUnlock()
- Does a read unlock.
One of the readers is done. If there are no more readers
then writing can begin again.
All Packages Class Hierarchy This Package Previous Next Index